Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@compute/src/main/java/org/zstack/compute/vm/VmAllocateNicFlow.java`:
- Around line 121-145: A VmNicVO is persisted by vnicFactory.createVmNic(nic,
spec) before callBeforeAllocateVmNicExtensions(...) but on extension failure the
code only records the error and doesn't remove that persisted nic, leaving an
orphaned VmNicVO/ResourceVO; in the Completion.fail(ErrorCode) branch delete the
persisted nicVO (and associated ResourceVO/any created system tags) inside a DB
transaction/SQLBatch (use dbf.remove(...) or equivalent) before adding the error
and calling wcomp.allDone(), ensuring the cleanup references the nicVO created
earlier so the rollback won't leave orphaned records.

In `@core/src/main/java/org/zstack/core/rest/webhook/WebhookCallbackClient.java`:
- Around line 101-109: The current submit method starts the timeout task via
thdf.submitTimeoutTask before putting the PendingEntry into pendingCalls, which
can race (timeout may run before put) and drop completion; fix by creating and
registering the PendingEntry in pendingCalls first (e.g., new
PendingEntry<>(completion, null) and put it), then call thdf.submitTimeoutTask
and store the returned TimeoutTaskReceipt into that PendingEntry (or replace the
entry with one containing the receipt). Update references: method submit, map
pendingCalls, class PendingEntry, thdf.submitTimeoutTask, fail/operr and
protocol.getCallbackPath() so the timeout handler will always find and remove
the registered entry.

In `@docs/modules/network/pages/networkResource/ZnsIntegration.adoc`:
- Around line 15-29: The example marked [source,go] is not valid Go: replace the
inline `###` comments with proper Go comments or remove them, add the missing
`struct` keyword for `type Segment` and ensure the slice field is declared
correctly (e.g., `CmsMetaDatas []Cms` with a proper struct tag like
`json:"cms"`), and make field names/types conform to Go syntax in the `Cms`
struct (e.g., ensure fields like `CmsUuid`, `Type`, `IP`, `Role`,
`CmsResourceUuid` use valid types and optional `json` tags); alternatively, if
you intend pseudocode, change the block language from `go` to something like
`text` and add a note that it’s pseudocode so readers aren’t misled.

In
`@header/src/main/java/org/zstack/header/vm/AfterReleaseVmNicExtensionPoint.java`:
- Around line 10-11: 为 AfterReleaseVmNicExtensionPoint 接口的 afterReleaseVmNic
方法添加方法级 Javadoc，说明回调契约：明确在何种时机框架会调用 afterReleaseVmNic，要求扩展实现必须在处理完成后且仅调用一次
Completion（调用 completion.success() 表示成功、调用 completion.fail(Throwable)
表示失败），不应阻塞调用线程或抛出未捕获异常，并说明是否允许异步完成及线程/事务约束；同时移除方法声明中多余的 public
修饰符以符合接口方法规范（定位符：AfterReleaseVmNicExtensionPoint.afterReleaseVmNic(VmNicInventory
nic, Completion completion)）。

In `@network/src/main/java/org/zstack/network/l3/L3NetworkManagerImpl.java`:
- Line 197: 在 L3NetworkManagerImpl 中避免直接对 dbf.findByUuid(...) 的返回值调用
L3NetworkInventory.valueOf(...) 导致 NPE：先把 dbf.findByUuid(msg.getL3NetworkUuid(),
L3NetworkVO.class) 的结果赋给一个局部变量（例如 vo 或 l3Vo），对该变量判空；若为 null，调用
trigger.fail(...)（包含清晰的错误信息和 msg.getL3NetworkUuid()）并返回；否则再调用
L3NetworkInventory.valueOf(...) 继续后续逻辑。

In `@plugin/kvm/src/main/java/org/zstack/kvm/KVMRealizeL2VlanNetworkBackend.java`:
- Around line 252-254: 当前在 KVMRealizeL2VlanNetworkBackend 的判断只为 dpdk
vhost-user（L2NetworkConstant.ACCEL_TYPE_VHOST_USER_SPACE）设置 srcPath，遗漏了
vDPA（L2NetworkConstant.ACCEL_TYPE_VDPA），导致 NIC 未被正确配置；在包含 to.setSrcPath(...)
的分支中扩展条件为同时匹配 ACCEL_TYPE_VHOST_USER_SPACE 或 ACCEL_TYPE_VDPA（检查 nic.getType()），使
to.setSrcPath 使用 L2NetworkConstant.OVN_DPDK_VNIC_SRC_PATH +
nic.getInternalName() 对两类加速 NIC 都生效；并在 KVMRealizeL2NoVlanNetworkBackend
中对称地做同样的修改以保持行为一致。

In
`@plugin/sdnController/src/main/java/org/zstack/sdnController/SdnControllerManagerImpl.java`:
- Around line 273-279: The current try/catch in SdnControllerManagerImpl around
tagMgr.createTagsFromAPICreateMessage(...) and dbf.findByUuid(...) silently
swallows initialization failures and still calls publish(event); remove the
catch so failures propagate (or rethrow the exception) instead of continuing on
the success path, ensuring event.setInventory(...) and tag creation errors
prevent publish(event) from returning success; locate the block that calls
tagMgr.createTagsFromAPICreateMessage(...), dbf.findByUuid(...), and
event.setInventory(...) and delete the surrounding try/catch (or replace with a
rethrow) so errors are not suppressed.
- Around line 661-680: The loop building nicMaps in SdnControllerManagerImpl
(currently iterating nics and calling dbf.findByUuid for L3NetworkVO and
L2NetworkVO and reading L2_NETWORK_SDN_CONTROLLER_UUID tag per NIC) causes N+1
queries; refactor by adding a batch helper (e.g., buildNicToControllerMap or
resolveNicsToControllers) that: collects all l3 uuids from the nics, does a
single dbf.listByIds/findByUuids for L3NetworkVO, collects all referenced l2
uuids and batch-fetches L2NetworkVOs, then resolves controllerUuid tokens for
those L2s in one pass and returns a Map<controllerUuid, List<VmNicInventory>>;
replace the three similar loops (around the shown block and at ranges 698-717,
734-753) to call this helper and handle null/missing controllerUuid by failing
the completion once with the same operr message referencing l2 uuid.
- Around line 663-670: The loop that looks up L3NetworkVO and L2NetworkVO should
fail-fast instead of silently continuing: when
dbf.findByUuid(nic.getL3NetworkUuid(), L3NetworkVO.class) or
dbf.findByUuid(l3Vo.getL2NetworkUuid(), L2NetworkVO.class) returns null, stop
processing and fail the allocation (e.g., call completion.fail or throw an
exception) with a clear error message including the missing UUID and NIC info;
do not let nicMaps remain empty and return completion.success(). Update the
logic around shouldSkipSdnForNic to still allow skipping when intentional, but
treat null VO results as fatal data-inconsistency errors and surface them
immediately.

In `@rest/src/main/resources/scripts/RestDocumentationGenerator.groovy`:
- Around line 2846-2849: The loop currently only catches CloudRuntimeException
when calling checkMD(mdPath, it.value), so other runtime exceptions (e.g.,
IndexOutOfBoundsException, NullPointerException thrown from checkMD or
getExistGlobalConfigMarkDown) will break the loop and prevent collecting all
errors; update the try/catch to catch Exception (or RuntimeException) in
addition to CloudRuntimeException around the call sites (checkMD and any calls
to getExistGlobalConfigMarkDown) and add their messages to allErrors (preserving
existing CloudRuntimeException behavior) so the loop continues and aggregates
every markdown validation failure.
- Around line 851-861: 当前校验用的是 markDown.desc_CN.isEmpty() 等判断，但
GlobalConfigMarkDown 是从 new GlobalConfigMarkDown() 开始解析，默认值为 "PLACEHOLDER..."，所以
.isEmpty() 会漏报未出现的 section。更新校验逻辑（在 RestDocumentationGenerator.groovy 中处理
getExistGlobalConfigMarkDown 返回的 GlobalConfigMarkDown）改为使用一个辅助判空方法（例如
isMissingField(String s)）并在该方法中同时判断 null、trim().isEmpty() 和是否以
"PLACEHOLDER"（或项目中实际的占位符前缀）开头，替换对
desc_CN、name_CN、valueRangeRemark、defaultValueRemark、resourcesGranularitiesRemark、additionalRemark、backgroundInformation、isUIExposed、isCLIExposed
的所有 .isEmpty() 调用；或者相应地修改 getExistGlobalConfigMarkDown 使未在 markdown 中出现的字段返回
null，并据此做相同的判定。

---

Nitpick comments:
In `@header/src/main/java/org/zstack/header/network/l3/L3NetworkVO.java`:
- Around line 118-120: Extract the repeated type-checking logic into a single
static helper on L3NetworkType and call it from both L3NetworkVO and
L3NetworkInventory.enableIpAddressAllocation(): move the if
(L3NetworkType.hasType(getType())) { return
L3NetworkType.valueOf(getType()).isIpAddressAllocationEnabled(); } logic into a
new L3NetworkType.static method (e.g., isIpAddressAllocationEnabled(String type)
or isIpAddressAllocationEnabledFor(String type)) that performs the hasType check
and returns the flag, then replace the existing branches in L3NetworkVO and
L3NetworkInventory.enableIpAddressAllocation() to delegate to that new static
method to avoid duplication and future drift.

In
`@header/src/main/java/org/zstack/header/vm/AfterReleaseVmNicExtensionPoint.java`:
- Around line 6-11: The interface AfterReleaseVmNicExtensionPoint and its method
afterReleaseVmNic currently mix "Release" in the name with "deleted from
database" in the Javadoc; update either the name or the comment so lifecycle
semantics match: either rename the interface/method to
DeletedVmNicExtensionPoint/afterDeletedVmNic if it is invoked after DB deletion,
or change the Javadoc to state the exact "release" stage (e.g., resource
release/cleanup before/after DB deletion) if the name is correct; make the
change where AfterReleaseVmNicExtensionPoint and afterReleaseVmNic are declared
and ensure VmNicInventory references and any callers/registrations are updated
consistently to avoid mismatched lifecycle semantics.

In `@plugin/kvm/src/main/java/org/zstack/kvm/KVMHost.java`:
- Around line 4183-4184: Replace the magic strings used when configuring ZNS
ports by extracting them into constants: replace the literal "br-int" passed to
to.setBridgeName and "openvswitch" passed to to.setBridgePortType with
class-level constants (e.g., BRIDGE_NAME_INT and BRIDGE_PORT_TYPE_OPENVSWITCH)
declared in KVMHost (or a shared constants class) and use those constant names
in the calls to to.setBridgeName(...) and to.setBridgePortType(...); ensure the
constants are public/static/final and documented so all usages reference the
single source of truth.

In `@testlib/src/main/java/org/zstack/testlib/SdnControllerSpec.groovy`:
- Around line 62-64: 在使用 JSONObjectUtil.rehashObject(querySdnController {
conditions=["uuid=${inventory.uuid}".toString()] }[0],
SdnControllerInventory.class) 之前不要直接取索引 0；在 SdnControllerSpec 的 postCreate
流程里先检查 querySdnController 返回的结果是否为 null 或为空列表（例如检查变量或返回值的
size/empty），若为空则抛出或记录一个明确的错误（包含 inventory.uuid 和上下文信息），否则再取第一项并传入
JSONObjectUtil.rehashObject 转换为 SdnControllerInventory。

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@compute/src/main/java/org/zstack/compute/vm/VmCascadeExtension.java`:
- Around line 339-343: The current L2 delete flow first derives l3Uuids via
Q.New(L3NetworkVO).in(L3NetworkVO_.l2NetworkUuid, l2Uuids) and later re-queries
NIC/VMs using nic.l3NetworkUuid, but VmNicVO.l3NetworkUuid is SET_NULL on L3
delete so NICs can be missed if L3s were processed earlier; instead, compute the
affected VmNic/VM set once up-front for the L2 cascade (e.g. query VmNicVO by
the L2 identifier(s) or by joined criteria that do not rely on L3NetworkVO
existence), store that NIC/VM list (used where msgs is built) and reuse it in
subsequent steps instead of re-querying via L3NetworkVO/l3.uuid so the detach
logic always runs for those NICs/VMs.

---

Nitpick comments:
In `@compute/src/main/java/org/zstack/compute/vm/VmCascadeExtension.java`:
- Around line 722-739: The new anonymous Callable in VmCascadeExtension
introduces a raw TypedQuery JPQL branch to fetch VMs by L2 network UUIDs;
extract this into a shared helper (e.g., queryVmsByNetworkRange or
findVmsByL2NetworkUuids) and reimplement it using the project-standard
Q.New(...) / SQL.New(...) API used by the existing L3 branch, reusing the same
filters (vm.type == VmInstanceConstant.USER_VM_TYPE, vm.state in {Stopped,
Paused, Running, Destroyed}, join through VmNicVO -> L3NetworkVO -> L2Network
UUIDs) instead of adding another TypedQuery; update the Callable to call that
helper and remove the JPQL string so the code follows the coding guideline of
avoiding TypedQuery.

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@compute/src/main/java/org/zstack/compute/vm/VmDetachNicFlow.java`:
- Around line 44-45: Remove the unused injected field VmInstanceManager vmMgr
from the VmDetachNicFlow class; locate the private field declaration "private
VmInstanceManager vmMgr" annotated with `@Autowired` in VmDetachNicFlow and delete
that field and its `@Autowired` annotation to clean up unused code and imports.
- Around line 120-125: The callReleaseSdnNics method in VmDetachNicFlow only
checks whether extension list is empty but omits the defensive check for an
empty nics list (VmReturnReleaseNicFlow.callReleaseSdnNics also checks
nics.isEmpty()); update VmDetachNicFlow.callReleaseSdnNics to return
completion.success() when either
pluginRgty.getExtensionList(AfterAllocateSdnNicExtensionPoint.class) is empty OR
the passed-in nics list is empty, mirroring the logic in VmReturnReleaseNicFlow
and preventing unnecessary extension invocation when nics is empty.

In `@compute/src/main/java/org/zstack/compute/vm/VmReturnReleaseNicFlow.java`:
- Around line 40-41: Remove the unused injected field by deleting the protected
VmInstanceManager vmMgr declaration (including its `@Autowired` annotation) from
the VmReturnReleaseNicFlow class; also remove any now-unused import for
VmInstanceManager and ensure there are no remaining references to vmMgr
elsewhere in this class.
- Around line 120-146: The callReleaseSdnNics implementation is duplicated
between VmReturnReleaseNicFlow and VmDetachNicFlow; extract the shared logic
into a single reusable utility or base method (e.g., a static helper in a new
SdnNicReleaseUtils or a protected method on a common base class) that accepts
List<VmNicInventory> nics, PluginRegistry/PluginRgty access, and a Completion,
and have both VmReturnReleaseNicFlow.callReleaseSdnNics and
VmDetachNicFlow.delegate to that new method; ensure the helper uses the same
AfterAllocateSdnNicExtensionPoint iteration,
Completion/While/WhileDoneCompletion behavior, and logging semantics so callers
simply forward nics and completion to the consolidated routine.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@compute/src/main/java/org/zstack/compute/vm/VmReturnReleaseNicFlow.java`:
- Line 84: The call to dbf.findByUuid(nic.getUuid(), VmNicVO.class) in
VmReturnReleaseNicFlow can return null when a NIC was already deleted; avoid
adding nulls to nicsToDelete and prevent NPEs by checking the result (VmNicVO)
before adding it to nicsToDelete, e.g., only add when non-null, or filter the
list prior to calling nicsToDelete.forEach(dbf::remove); ensure references to
dbf.remove and nicsToDelete are protected by this null check.

---

Outside diff comments:
In `@network/src/main/java/org/zstack/network/l2/L2NetworkApiInterceptor.java`:
- Around line 157-252: The interceptor currently allows targetIsGeneve to pass
initial type check but lacks a corresponding validation branch; add a branch for
targetIsGeneve in the ChangeL2NetworkVlanId handling (near the existing
targetIsVlan / targetIsNoVlan branches) that enforces Geneve-specific rules:
require/validate VNI (use msg.getVni or the proper VNI accessor), forbid
changing L2 type where applicable, run the same cluster/physical-interface
conflict checks as other branches if relevant, and throw the appropriate
ApiMessageInterceptionException using the existing error codes (e.g.
ORG_ZSTACK_NETWORK_ZNS_10014 or other defined codes) when validation fails;
alternatively, if Geneve validation is delegated to ZNS module, add a clear
comment and an explicit no-op branch for targetIsGeneve referencing that
delegation so the behavior is explicit.

---

Nitpick comments:
In `@compute/src/main/java/org/zstack/compute/vm/VmDetachNicFlow.java`:
- Line 101: 在 callReleaseSdnNics 调用处使用了全限定名
java.util.Collections.singletonList(nic)；请在文件顶部添加 import java.util.Collections;
并将该调用替换为 Collections.singletonList(nic) 以保持项目的导入风格一致并提高可读性；定位符参考：方法调用
callReleaseSdnNics(...) 和参数 singletonList 的替换位置。
- Around line 44-47: 类 VmDetachNicFlow 中注入的字段 vmMgr 未被使用，请删除该字段声明（private
VmInstanceManager vmMgr;）及其相关注入注解，确保同时移除任何不再需要的导入或引用，以保持类只保留实际使用的注入（例如
PluginRegistry pluginRgty）；保存并运行编译/静态检查以确认没有残留引用。
- Around line 120-146: The callReleaseSdnNics implementation in VmDetachNicFlow
is duplicated from VmReturnReleaseNicFlow; extract the shared logic that queries
pluginRgty for AfterAllocateSdnNicExtensionPoint and runs the While<> loop into
a single reusable method (e.g., VmInstanceManager.releaseSdnNics or a
SdnNicHelper.releaseSdnNics) that accepts List<VmNicInventory> and Completion,
move the While<>/ext.releaseSdnNics handling there, and replace the duplicate
implementations in VmDetachNicFlow and VmReturnReleaseNicFlow with calls to the
new shared method (keeping the same error handling behavior and use of
pluginRgty and AfterAllocateSdnNicExtensionPoint).

In `@compute/src/main/java/org/zstack/compute/vm/VmReturnReleaseNicFlow.java`:
- Around line 40-43: The injected field VmInstanceManager vmMgr in class
VmReturnReleaseNicFlow is never used; remove the unused `@Autowired` field
declaration (VmInstanceManager vmMgr) from VmReturnReleaseNicFlow and also
remove any now-unused import of VmInstanceManager if present to keep the code
clean.
- Around line 120-146: VmReturnReleaseNicFlow.callReleaseSdnNics duplicates
logic found in VmDetachNicFlow.callReleaseSdnNics; extract the shared iteration
over AfterAllocateSdnNicExtensionPoint and its Completion handling into a single
reusable method (either a new static helper in a shared utility class or an
instance method on VmInstanceManager) and replace both
VmReturnReleaseNicFlow.callReleaseSdnNics and VmDetachNicFlow.callReleaseSdnNics
to delegate to that new method; ensure the new method signature accepts
List<VmNicInventory> and a Completion and preserves the existing behavior (early
return when extensions or nics are empty, warn-on-fail, call
completion.success() on done).

In `@network/src/main/java/org/zstack/network/l2/L2NetworkApiInterceptor.java`:
- Line 4: Remove the unused import org.apache.poi.util.StringUtil from
L2NetworkApiInterceptor (the class referenced is L2NetworkApiInterceptor.java) —
the code already uses org.apache.commons.lang.StringUtils, so delete the unused
org.apache.poi.util.StringUtil import to clean up imports and avoid warnings.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@compute/src/main/java/org/zstack/compute/vm/VmDetachNicFlow.java`:
- Around line 127-143: In VmDetachNicFlow, the releaseSdnNics call inside the
new While<>(exts).each(...) swallows failures (logger.warn and always
wcomp.done()) and the enclosing WhileDoneCompletion always calls
completion.success(), allowing NIC DB deletion to proceed; change the failure
handling in the Completion passed to ext.releaseSdnNics so that on
fail(ErrorCode) you propagate the error to the outer completion (e.g.,
collect/forward the ErrorCode into the WhileDoneCompletion and call
completion.fail(...)) instead of only logging, or alternatively persist a
compensation/retry record before allowing completion.success() to proceed;
update the Completion.fail path and the WhileDoneCompletion.done(...) logic to
ensure failures from releaseSdnNics prevent unconditional completion.success()
and trigger retry/compensation handling.

In `@compute/src/main/java/org/zstack/compute/vm/VmReturnReleaseNicFlow.java`:
- Around line 127-143: In VmReturnReleaseNicFlow, the ext.releaseSdnNics(...)
fail handler currently only logs and calls wcomp.done(), and the outer
WhileDoneCompletion always calls completion.success(), which lets callers delete
local VmNicVO even when SDN release failed; change the flow to propagate errors:
collect ErrorCodes from ext.releaseSdnNics within the While (or record failures
in a shared ErrorCodeList), and in WhileDoneCompletion.done inspect that list
and call completion.fail(...) with a composed ErrorCode when any SDN release
failed (or alternatively enqueue a compensating retry task before returning
success); ensure changes touch the ext.releaseSdnNics fail path, the
WhileDoneCompletion.done logic that currently calls completion.success(), and
the completion passed into VmReturnReleaseNicFlow so the caller receives
failures instead of silent success.

---

Duplicate comments:
In `@compute/src/main/java/org/zstack/compute/vm/VmReturnReleaseNicFlow.java`:
- Around line 84-113: The code in VmReturnReleaseNicFlow calls
dbf.findByUuid(...) which can return null; avoid NPE by filtering out missing
VmNicVOs before using or adding them to nicsToDelete/releasedNics: when
dbf.findByUuid(nic.getUuid(), VmNicVO.class) returns null, skip that nic
(optionally log a warning) and do not add null to nicsToDelete or releasedNics,
and ensure the later callSite that removes entries
(nicsToDelete.forEach(dbf::remove)) only iterates real VmNicVO instances; update
the loop that builds nicsToDelete/releasedNics around callReleaseSdnNics
accordingly.